docs(education): add AI tutor discoverability to education and training READMEs - #927
Conversation
…ng READMEs Add a "Learn with an AI tutor" section to docs/education/README.md and docs/education/training/README.md, pointing learners to ai-tutors/README.md with brief how-to-load instructions (paste below the --- separator as the system prompt). Confirms ai-tutors/README.md already lists all eleven lessons. Generated-by: Claude (claude-sonnet-4-6)
potiuk
left a comment
There was a problem hiding this comment.
LGTM — useful discoverability fix, and the coverage claim holds up. Two observations below, neither gating.
I checked the claim rather than assuming it, since "each lesson has a matching tutor" is the kind of thing that quietly stops being true:
docs/education/README.md's progression lists 11 numbered pages;ai-tutors/has 11lesson-*.mdfiles, and they line up 1:1 by name (what-agents-are→lesson-01-what-agents-are, throughcontributing→lesson-11-how-to-contribute). The training module map is also 11.- The two supporting references (pattern catalogue, tutorials) have no tutors, but they are explicitly not lessons in the progression, so the wording is accurate.
- The three tools named — claude.ai Projects, Open WebUI, API — match what
ai-tutors/README.mdactually documents. - Both relative paths resolve, and the doctoc entries were added alongside the headings.
Smaller observations
-
the --- separatoris ambiguous, and following it literally breaks the tutor. Every one of the eleven lesson files contains exactly two---lines: the first splits reader-notes from the tutor prompt, and the second sits inside the prompt, dividing the tutor instructions from## KNOWLEDGE BASE. A reader told to "find the---separator" who lands on the second pastes only the knowledge base and loses the entire tutor persona — a failure that looks like the prompt simply not working.One word fixes it:
**How to load a tutor:** open the matching `lesson-*.md` file under `ai-tutors/`, find the **first** `---` separator, and paste everything below that line as the system prompt.Worth knowing this is inherited, not introduced here:
ai-tutors/README.mdsays "Each file has two parts split by a---line", which has the same imprecision. So this PR propagates it into two more places rather than creating it. Fixing all three would be ideal; fixing the two new copies is the cheap half. -
Three copies of the loading procedure now exist. The how-to-load paragraph is duplicated into both READMEs verbatim, alongside the original in
ai-tutors/README.md. Given the separator wording above is already drifting from what the files contain, that is the concrete argument for a one-line pointer plus the link instead of a copy — the link cannot go stale, the paraphrase can. Not worth blocking a discoverability improvement over, but if the procedure changes again there are now three places to remember.
This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The maintainer
approving this PR has read the findings and signed off. If
something feels off, please reply on the PR and a maintainer
will follow up.More on how Apache Magpie handles maintainer review:
CONTRIBUTING.md § Opening a pull request.
Summary
Add a "Learn with an AI tutor" section to docs/education/README.md and docs/education/training/README.md, pointing learners to ai-tutors/README.md with brief how-to-load instructions (paste below the --- separator as the system prompt). Confirms ai-tutors/README.md already lists all eleven lessons.
Generated-by: Claude (claude-sonnet-4-6)
Type of change
.claude/skills/<name>/) — eval fixtures updated belowtools/<system>/*.md)tools/*/withpyproject.toml)docs/,README.md,CONTRIBUTING.md)projects/_template/)prek, workflows, validators)Test plan
prek run --all-filespassesuv run pytest/ruff check/mypypasses(
PYTHONPATH=tools/skill-evals/src python3 -m skill_evals.runner tools/skill-evals/evals/<skill>/)(a regression test for the bug fixed / the behaviour added — see CONTRIBUTING.md)